big_integer

An immutable signed integer type, supporting extremely large values (upwards of 100,000 decimal digits).

Literals of big_integer type can be written like integers, but with the suffix L, e.g. 123L or 0x123L. big_integers support the operators +, -, *, / and % with typical behavior.

Since

0.12.0

Constructors

Link copied to clipboard
pure constructor(s: text)

Construct a big_integer by parsing a signed base-10 text representation of an integer.

pure constructor(value: integer)

Construct a big_integer from an integer.

Properties

Link copied to clipboard
val MAX_VALUE: big_integer = 1e+131072

The maximum value a big_integer can have, (10^131072)-1.

Link copied to clipboard
val MIN_VALUE: big_integer = -1e+131072

The minimum value a big_integer can have, -(10^131072)+1.

Link copied to clipboard
val PRECISION: integer = 131072

The maximum number of digits a big_integer can have, 131072, or 2^17.

Functions

Link copied to clipboard
pure function abs(): big_integer

Returns the absolute value of this big_integer; i.e. the big_integer itself if it's positive or its negation if it's negative.

Link copied to clipboard
pure static function from_bytes(value: byte_array): big_integer

Create a big_integer from a byte array.

The byte array is interpreted with the first bit representing the sign (two's complement), and for subsequent bits, more significant bits are on the left and less significant bits are on the left (big-endian).

Inverse of big_integer.to_bytes().

Link copied to clipboard
pure static function from_bytes_unsigned(value: byte_array): big_integer

Create a big_integer from a byte array.

The byte array is interpreted with more significant bits on the left and less significant bits on the right (big-endian). An empty byte array is interpreted as 0.

Inverse of big_integer.to_bytes_unsigned().

Link copied to clipboard
pure static function from_hex(value: text): big_integer

Parses an unsigned hexadecimal text representation of a big_integer.

Base prefixes are not supported, so one must write e.g. integer.from_hex('CAFE') rather than integer.from_hex('0xCAFE').

Case is ignored, i.e. integer.from_hex('CAFE') and integer.from_hex('cafe') are equivalent.

Link copied to clipboard
pure static function from_text(value: text): big_integer

Parse a signed base-10 text representation of an integer.

pure static function from_text(value: text, radix: integer): big_integer

Parse a signed text representation of an integer. The integer is interpreted in the specified radix (from 2 to 36 inclusive).

Link copied to clipboard
pure function max(value: big_integer): big_integer

Returns the greater of this and another big_integer value; i.e. value if value is greater than this, or this big_integer otherwise.

pure function max(value: decimal): decimal

Returns the numerically greater of this big_integer a decimal value; i.e. value if value is greater than this big_integer, or this big_integer otherwise.

Link copied to clipboard
pure function min(value: big_integer): big_integer

Returns the lesser of this and another big_integer value; i.e. value if value is less than this, or this big_integer otherwise.

pure function min(value: decimal): decimal

Returns the numerically lesser of this big_integer a decimal value; i.e. value if value is less than this big_integer, or this big_integer otherwise.

Link copied to clipboard
pure function pow(exponent: integer): big_integer

Raise this big_integer to the power of the given exponent. SQL compatible.

Note that:

  • the exponent cannot be negative

  • if the exponent is 0, the result is 1

  • if the exponent is 1, the result is the original value

Link copied to clipboard
pure function sign(): integer

Returns the sign of this big_integer: -1 if negative, 0 if zero, and 1 if positive.

It holds that for all x, x == x.sign() * x.abs().

Link copied to clipboard
pure function to_bytes(): byte_array

Convert this big_integer to a byte array.

The first bit of the generated byte array represents the sign (two's complement), and for subsequent bits, more significant bits are on the left and less significant bits are on the left (big-endian).

Inverse of big_integer.from_bytes().

Examples:

  • 0L.to_bytes() returns x'00'

  • (-1L).to_bytes() returns x'FF'

  • 1L.to_bytes() returns x'01'

  • 2L.pow(100).to_bytes() returns x'10000000000000000000000000'

Link copied to clipboard
pure function to_bytes_unsigned(): byte_array

Convert this non-negative big_integer to a byte array, with no sign bit.

The generated byte array has more significant bits on the left and less significant bits on the right (big-endian).

Inverse of big_integer.from_bytes_unsigned().

When this big_integer is equal to 0, the empty byte array x'' is returned (this is consistent with the inverse function big_integer.from_bytes_unsigned(), which interprets x'' as 0).

Examples:

  • 0L.to_bytes_unsigned() returns x''

  • (-1L).to_bytes_unsigned() throws an exception

  • 1L.to_bytes_unsigned() returns x'01'

  • 2L.pow(100).to_bytes_unsigned() returns x'10000000000000000000000000'

Link copied to clipboard
pure function to_decimal(): decimal

Convert this big_integer to a decimal.

Link copied to clipboard
pure function to_hex(): text

Convert this big_integer to hexadecimal text.

Does not include a base prefix in the output, i.e. big_integer(25).to_hex() returns 19 rather than 0x19.

Link copied to clipboard
pure function to_integer(): integer

Convert this big_integer to an integer.

Link copied to clipboard
pure function to_text(): text

Convert this big_integer to a base 10 text representation.

pure function to_text(radix: integer): text

Convert this big_integer to a text representation with the specified radix.

Does not include a base prefix in the output, i.e. integer(25).to_text(16) returns 19 rather than 0x19.

Supported radixes are from 2 to 36 (inclusive).